WildFly Configuration

If you are using WildFly 8.0.1.Final, this article works perfectly.

If you are using WildFly 8.0.0.Final, please read the WildFly 8.0.0.Final Notes for more details.

Introduction

This page will guide you on how to configure your IdPs and SPs when using WildFly.

Before you start, you should keep in mind that you must use PicketLink 2.6.0.CR1 and beyond. At the time this page is was written, the lastest WildFly version was 8.0.0.Final, which is shipped with PicketLink 2.5.2.Final. Future WildFly versions will be properly updated with the PicketLink version and modules configuration.

Identity Provider Configuration

To configure your application as an Identity Provider you need to:

Configure your WEB-INF/web.xml with the PicketLink IDP Servlet Filter, security-constraint and login-config
Configure your WEB-INF/jboss-web.xml with a security-domain.
Configure your META-INF/jboss-deployment-structure.xml with the PicketLink Federation module dependencies.
Configure your WEB-INF/picketlink.xml with all the PicketLink configuration accordingly to your requirements.

You can also take a look at our quickstarts, which provide some ready to use examples with all the necessary configuration to get an IdP up and running.

https://github.com/jboss-developer/jboss-picketlink-quickstarts

Take a look at the following documentation for more details about each example:

https://github.com/jboss-developer/jboss-picketlink-quickstarts#about-the-picketlink-federation-quickstarts

Each quickstart provides a README.md file with a lot of useful information about how to build and deploy them.

Configuring the Web Deployment Descriptor (WEB-INF/web.xml)

To enable PicketLink to your IdP you will need the following changes to your WEB-INF/web.xml.

<!-- The IDPFilter is responsible for enabling all SAML processing. -->
<filter>
    <filter-name>IDPFilter</filter-name>
    <filter-class>org.picketlink.identity.federation.web.filters.IDPFilter</filter-class>
</filter>

<filter-mapping>
    <filter-name>IDPFilter</filter-name>
    <url-pattern>/*</url-pattern>
</filter-mapping>

<!-- Define a security constraint that gives unlimited access to some static resources. -->
<security-constraint>
    <web-resource-collection>
        <web-resource-name>Images</web-resource-name>
        <url-pattern>/images/*</url-pattern>
    </web-resource-collection>
    <web-resource-collection>
        <web-resource-name>CSS</web-resource-name>
	<url-pattern>/css/*</url-pattern>
    </web-resource-collection>
</security-constraint>

<!-- Define a Security Constraint on this application. -->
<security-constraint>
    <web-resource-collection>
        <web-resource-name>Manager command</web-resource-name>
        <url-pattern>/*</url-pattern>
    </web-resource-collection>
    <auth-constraint>
        <role-name>manager</role-name>
	<role-name>Sales</role-name>
	<role-name>Employee</role-name>
    </auth-constraint>
</security-constraint>

<!-- Define the Login Configuration for this application. -->
<login-config>
    <auth-method>FORM</auth-method>
    <realm-name>PicketLink IDP Application</realm-name>
    <form-login-config>
        <form-login-page>/jsp/login.jsp</form-login-page>
	<form-error-page>/jsp/login-error.jsp</form-error-page>
    </form-login-config>
</login-config>

<!-- Security roles referenced by this web application. -->
<security-role>
    <role-name>manager</role-name>
</security-role>
<security-role>
    <role-name>Sales</role-name>
</security-role>
<security-role>
    <role-name>Employee</role-name>
</security-role>

Configuring the Security Domain

The security domain is used to authenticate your users. To reference a security domain from your deployment you need to change the WEB-INF/jboss-web.xml file as follows:

<jboss-web>
    <!-- You must have a security-domain configured in your JBoss EAP instance. The security-domain is necessary to provide user authentication and roles mappings. -->
    <security-domain>idp</security-domain>

    <!-- Here we just define the context path of the deployment. -->
    <context-root>idp</context-root>
</jboss-web>

The configuration above is telling that the application will use the idp security domain to authenticate users. All the security domain configuration is defined in the JBOSS_HOME/standalone/configuration/standalone.xml by the Security Subsystem.

The example below is a very simple example of a security domain that can be used by an IdP to authenticate users using properties file to match username/passwords and their respective roles:

<security-domain name="idp" cache-type="default">
    <authentication>
        <login-module code="UsersRoles" flag="required">
            <module-option name="usersProperties" value="users.properties"/>
            <module-option name="rolesProperties" value="roles.properties"/>
        </login-module>
    </authentication>
</security-domain>

WildFly provides a plenty of JAAS LoginModules using LDAP and Databases to authenticate users. Make sure you're using the implementation which most fits your requirements.

Configuring the PicketLink Dependencies

WildFly is shipped with all the necessary PicketLink libraries, configured as modules. Please take a look at WildFly and JBoss Modules for more details.

You don't need to package your application with the PicketLink jars, but only configure the PicketLink dependencies in your META-INF/jboss-deployment-structure.xml as follows:

<jboss-deployment-structure>
    <deployment>
        <!-- You must configure the PicketLink dependency to your deployment. The dependency above is a reference to a static module from WildFly modules directory. -->
        <dependencies>
            <module name="org.picketlink"/>
        </dependencies>
    </deployment>
</jboss-deployment-structure>

PicketLink Identity Provider Configuration

All the configuration for your IdP is read from the WEB-INF/picketlink.xml. This file defines all the configuration to your IdP like signature support, encryption, trusted domains, etc.

Please take a look at the PicketLink Identity Provider (PIDP) for more details.

Service Provider Configuration

To configure your application as Service Provider you need to:

Configure your WEB-INF/web.xml with the security-constraint and login-config
Configure a Undertow Servlet Extension to enable SAML processing.
Configure your WEB-INF/jboss-web.xml with a security-domain.
Configure your META-INF/jboss-deployment-structure.xml with the PicketLink Federation module dependencies.
Configure your WEB-INF/picketlink.xml with all the PicketLink configuration accordingly to your requirements.

You can also take a look at our quickstarts, which provide some ready to use examples with all the necessary configuration to get an SP up and running.

https://github.com/jboss-developer/jboss-picketlink-quickstarts

Take a look at the following documentation for more details about each example:

https://github.com/jboss-developer/jboss-picketlink-quickstarts#about-the-picketlink-federation-quickstarts

Each quickstart provides a README.md file with a lot of useful information about how to build and deploy them.

Configuring the Web Deployment Descriptor (WEB-INF/web.xml)

To enable PicketLink to your SP you will need the following changes to your WEB-INF/web.xml.

<?xml version="1.0" encoding="ISO-8859-1"?>
<web-app xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
	version="2.5">

    <display-name>PicketLink Sales Service Provider</display-name>

    <description>PicketLink Service Provider With a Basic Configuration using SAML HTTP POST Binding</description>

    <!-- Define a Security Constraint on this Application -->
    <security-constraint>
        <web-resource-collection>
	    <web-resource-name>SALES Application</web-resource-name>
	    <url-pattern>/*</url-pattern>
	</web-resource-collection>
	<auth-constraint>
	    <role-name>manager</role-name>
	</auth-constraint>
    </security-constraint>

    <!-- Define a security constraint that gives unlimted access to freezone -->
    <security-constraint>
  	<web-resource-collection>
   	    <web-resource-name>freezone</web-resource-name>
	    <url-pattern>/freezone/*</url-pattern>
	</web-resource-collection>
	<web-resource-collection>
	    <web-resource-name>images</web-resource-name>
	    <url-pattern>/images/*</url-pattern>
	</web-resource-collection>
	<web-resource-collection>
   	    <web-resource-name>css</web-resource-name>
	    <url-pattern>/css/*</url-pattern>
	</web-resource-collection>
    </security-constraint>

    <!-- Define the Login Configuration for this Application -->
    <login-config>
 	<auth-method>FORM</auth-method>
	<realm-name>Tomcat SALES Application</realm-name>
	<form-login-config>
   	    <form-login-page>/jsp/login.jsp</form-login-page>
		<form-error-page>/jsp/loginerror.jsp</form-error-page>
	    </form-login-config>
	</login-config>

	<!-- Security roles referenced by this web application -->
	<security-role>
	    <description>The role that is required to log in to the Manager Application</description>
	    <role-name>manager</role-name>
	</security-role>
</web-app>

Configuring Undertow Servlet Extension

In order to get your deployment able to process SAML messages, you need to configure a WEB-INF/classes/META-INF/services/io.undertow.servlet.ServletExtension as follows:

org.picketlink.identity.federation.bindings.wildfly.sp.SPServletExtension

Configuring the Security Domain

The security domain is used to authenticate your users. To reference a security domain from your deployment you need to change the WEB-INF/jboss-web.xml file as follows:

<?xml version="1.0" encoding="UTF-8"?>
<jboss-web>
    <!-- You must have a security-domain configured in your JBoss EAP instance. The security-domain is necessary to provide user
    authentication and roles mappings. In this case,we need a specific JAAS LoginModule that knows how to extract user's information from a SAML Assertion previously
    issued by the Identity Provider. -->
    <security-domain>sp</security-domain>

    <!-- Here we just define the context path of the deployment. -->
    <context-root>sales-post</context-root>
</jboss-web>

The configuration above is telling that the application will use the sp security domain to authenticate users. All the security domain configuration is defined in the JBOSS_HOME/standalone/configuration/standalone.xml by the Security Subsystem.

Usually, the security domain used by a Service Provider looks like this:

<security-domain name="sp" cache-type="default">
    <authentication>
        <login-module code="org.picketlink.identity.federation.bindings.wildfly.SAML2LoginModule" flag="required"/>
    </authentication>
</security-domain>

The SAML2LoginModule is a JAAS Login Module provided by PicketLink which knows how to authenticate users based on a SAML Assertion previously issued by an IdP. This login module will extract all user information from the SAML Assertion and setup a security context for the user.

Configuring the PicketLink Dependencies

WildFly is shipped with all the necessary PicketLink libraries, configured as modules. Please take a look at WildFly and JBoss Modules for more details.

You don't need to package your application with the PicketLink jars, but only configure the PicketLink dependencies in your META-INF/jboss-deployment-structure.xml as follows:

<jboss-deployment-structure>
    <deployment>
        <!-- You must configure the PicketLink dependency to your deployment. The dependency above is a reference to a static module from WildFly modules directory. -->
        <dependencies>
            <module name="org.picketlink"/>
        </dependencies>
    </deployment>
</jboss-deployment-structure>

PicketLink Identity Provider Configuration
All the configuration for your IdP is read from the WEB-INF/picketlink.xml. This file defines all the configuration to your IdP like signature support, encryption, trusted domains, etc.
Please take a look at the PicketLink Identity Provider (PIDP) for more details.

PicketLink Identity Provider Configuration

All the configuration for your SP is read from the WEB-INF/picketlink.xml. This file defines all the configuration to your SP like signature support, encryption, etc.

Please take a look at the PicketLink Service Provider (PSP) for more details.

WildFly 8.0.0.Final Notes

In the past few days we've been working with a better integration between WildFly and PicketLink. This integration involves:

PicketLink Extension, providing a subsystem for both IDM and Federation
OOTB Support for SAML
PicketLink modules fully updated with the new structure and dependencies

Unfortunately, the changes we did to WildFly and PicketLink were done after WildFly 8.0.0.Final release. So you won't be able to use PicketLink with WildFly 8.0.0.Final without some additional steps. Basically, these steps are:

Download WildFly 8.0.0.Final Distribution ZIP File
Update/Replace Undertow libiraries with version 1.0.1.Final. For that, you can use a file attached to this page: io.undertow-jboss-modules-1.0.1.Final.zip. Just extract this file inside JBOSS_HOME/modules/system/layers/base/.
Use the PicketLink Installer to update the PicketLink Modules.
Check JBOSS_HOME//modules/system/layers/base/org/picketlink/federation/bindings/main/module.xml.

This steps are specially required for two reasons. First, the Undertow version shipped with WildFly 8.0.0.Final has an blocker issue that impacts PicketLink Federation features (specially our SAML support) to work properly. Second, the PicketLink modules must be updated to use latest version.

You must also make sure you have the following configuration in JBOSS_HOME/modules/system/layers/base/org/picketlink/federation/bindings/main/module.xml:

<module xmlns="urn:jboss:module:1.3" name="org.picketlink.federation.bindings">
    <resources>
        <resource-root path="picketlink-wildfly8-2.6.0-CR2.jar"/>
    </resources>

    <dependencies>
        <module name="javax.security.auth.message.api" />
        <module name="javax.security.jacc.api" />
        <module name="javax.transaction.api" />
        <module name="javax.xml.bind.api" />
        <module name="javax.xml.stream.api" />
        <module name="javax.servlet.api" />
        <module name="org.jboss.common-core" />
        <module name="org.jboss.logging" />
        <module name="org.wildfly.extension.undertow" />
        <module name="org.jboss.security.xacml" />
        <module name="org.picketbox" />
        <module name="javax.xml.ws.api" />
        <module name="org.apache.log4j" />
        <module name="org.apache.santuario.xmlsec">
            <imports>
                <exclude path="javax/*"/>
            </imports>
        </module>
        <module name="javax.api" />
        <module name="org.jboss.ws.api" />
        <module name="org.jboss.ws.spi" />
        <module name="org.apache.cxf" />
        <module name="io.undertow.core" />
        <module name="io.undertow.servlet" />
        <module name="org.picketlink.common" />
        <module name="org.picketlink.config" />
        <module name="org.picketlink.federation" />
    </dependencies>

</module>

If you're using WildFly 8.0.1+, PicketLink Federation will work OOTB. But we strongly recommend you to use the PicketLink Installer (step 3 above) to update the PicketLink modules with the latest version.